Add depends_on / related frontmatter to product-spec.md; surface in list#64
Merged
Add depends_on / related frontmatter to product-spec.md; surface in list#64
Conversation
… rules `draftwise init` now writes `.draftwise/constitution.md` on both the brownfield and greenfield paths. Five stable section headings — Voice, Spec language, Edge case discipline, Project conventions, Domain glossary — that every drafting prompt (`new`, `tech`, `tasks`, `scan`, `explain`, greenfield Phase 3) tells the host coding agent to read before drafting and apply by name. `scan` and the greenfield Phase 3 additionally instruct the agent to refine the **Project conventions** section from observed code / chosen stack, replacing the placeholder. This replaces the role that `src/ai/prompts/principles.js` and `src/ai/prompts/spec-quality.js` used to play before the api-mode drop. Those modules injected collaboration + spec-language rules into every system prompt; with synthesis moved entirely into the host coding agent, the rules now live in the user's repo as a markdown file the agent reads on each call. The file is user-editable and version-controlled, so changes are reviewable and travel with the repo. Reader utility at `src/utils/constitution.js` (`readConstitution(cwd)` returns null on ENOENT, propagates other errors); template at `src/utils/constitution-template.js`. Every prompt that references the file says "skip silently if absent" — back-compat for projects that ran `init` before this feature landed. CLAUDE.md and README.md updated end-to-end (key design principles, src/utils list, "What gets installed" tree). CHANGELOG.md `[Unreleased] ### Added` entry documents the rationale and the section structure.
…ce in `list`
`draftwise new`'s instruction now tells the host coding agent to open `product-spec.md` with an optional YAML frontmatter block — `depends_on: [<slug>...]` for specs that must ship before this one, `related: [<slug>...]` for same-area specs that aren't a hard dependency. The agent is told to list `.draftwise/specs/` first and reference only slugs that exist on disk; if there are no other specs yet, the block is skipped. This applies on both the brownfield and greenfield phase-3 instructions.
`draftwise list` grew a fourth column — DEPENDS ON — between STATUS and TITLE. Specs without frontmatter or without a `depends_on` key show blank.
Frontmatter parsing lives in a new `src/utils/frontmatter.js` (small wrapper over the `yaml` package — handles CRLF, malformed YAML, and non-object roots by returning empty data so a broken spec doesn't break the whole list).
Why: cross-spec dependencies were a deferred-for-later item in CLAUDE.md, but the cheap version — declarative in the spec, surfaced in `list` — answers the actual PM question ("which specs are ready to start?") without the heavier machinery (drift detection, ripple analysis, graph traversal). Living in a frontmatter block keeps it out of the rendered spec body and lets the agent regenerate it on `refine` later.
CLAUDE.md gets a "Cross-spec dependencies live in product-spec frontmatter" key principle and an updated `src/utils/` listing. README.md's "Product spec sections" section gets the frontmatter example block. CHANGELOG.md `[Unreleased] ### Added` documents the rationale.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
draftwise new's instruction now tells the host coding agent to write an optional YAML frontmatter block (depends_on: [<slug>...],related: [<slug>...]) at the top ofproduct-spec.md. The agent is told to list.draftwise/specs/first and reference only slugs that exist; if no other specs exist yet, the block is skipped. Both brownfield and greenfield phase-3 instructions updated.draftwise listgrew a fourth column — DEPENDS ON — between STATUS and TITLE.src/utils/frontmatter.js(small wrapper overyaml); handles CRLF, malformed YAML, and non-object roots by falling back to empty data so a broken spec file doesn't break the whole list.Stacking
Stacked on
feat/constitution(PR #63). Merge that one first; this branch will rebase onto main once it lands.Test plan
npx vitest run— 241 tests pass (12 new acrosstest/utils/frontmatter.test.js+test/commands/list.test.js)npm run lintclean---\ndepends_on: [auth]\n---\n\n# Profile\nto a seeded spec; confirmdraftwise listshowsauthin the DEPENDS ON column